/******************************************************************************
 * @file si_adda.c
 * @brief ADDA集成模块实现文件
 *
 * 详细描述：
 * - 功能1：实现ADDA系统硬件接口与OS接口的绑定
 * - 功能2：提供队列操作、延时函数等ADDA处理器所需的OS服务
 * - 功能3：初始化ADDA输入参数结构体，整合所有必要资源
 *
 * @author 陈泳行 | R&D Dept. | Jin Dou Aerospace 金斗航天
 * @date 2025-6-29
 * @version 1.0.0
 *
 * @version_history
 * - 1.0.0 (2025-6-29): 初始版本，实现基本功能
 *
 * @note 本模块必须在FreeRTOS环境下使用
 * @warning 结构体初始化顺序必须严格遵循依赖关系
 ******************************************************************************/
#include "si_adda.h"


/**
 * @brief 时间基接口结构体实例
 * @details 绑定HAL_GetTick函数作为系统时间基准
 */
time_base_t       time_base = 
{
	.pftime_base = HAL_GetTick,
};

/**
 * @brief OS延时接口结构体实例
 * @details 绑定FreeRTOS的vTaskDelay函数实现延时功能
 */
os_delay_t        os_delay  =
{
	.pfos_delay  = vTaskDelay,
};

/**
 * @brief 创建ADDA事件队列
 * @details 封装FreeRTOS的xQueueCreate函数，创建指定大小的事件队列
 * 
 * @param[out] queue_handle 输出参数，队列句柄指针
 * @param[in] queue_size 队列容量，可容纳的元素数量
 * @param[in] item_size 每个队列元素的大小（字节）
 * 
 * @return adda_handler_ret_t 操作结果
 * @retval ADDA_HANDLER_RET_OK 队列创建成功
 * @retval ADDA_HANDLER_RET_ERROR 队列创建失败（内存不足）
 */
adda_handler_ret_t adda_queue_create (void** queue_handle, 
									  uint32_t queue_size, 
									  uint32_t item_size  )
{
	QueueHandle_t handle_queue;
    handle_queue = xQueueCreate(queue_size,
							    item_size  );
    if(NULL == handle_queue)
    {
        return ADDA_HANDLER_RET_ERROR;
    }
    *queue_handle = handle_queue;
    return ADDA_HANDLER_RET_OK;
}

/**
 * @brief 删除ADDA事件队列
 * @details 封装FreeRTOS的vQueueDelete函数，安全删除指定队列
 * 
 * @param[in] queue_handle 要删除的队列句柄
 * 
 * @return adda_handler_ret_t 操作结果
 * @retval ADDA_HANDLER_RET_OK 队列删除成功
 * @retval ADDA_HANDLER_RET_ERROR 无效的队列句柄
 */
adda_handler_ret_t adda_queue_delete (void* queue_handle  )
{
	if( NULL  == queue_handle )
	{
		return ADDA_HANDLER_RET_ERROR;
	}
	vQueueDelete(queue_handle);
	return ADDA_HANDLER_RET_OK;
}

/**
 * @brief 发送数据到ADDA事件队列
 * @details 封装FreeRTOS的xQueueSendToBack函数，向队列尾部发送数据
 * 
 * @param[in] queue_handle 队列句柄
 * @param[in] item 要发送的数据指针
 * @param[in] timeout_ms 超时时间（毫秒）
 * 
 * @return adda_handler_ret_t 操作结果
 * @retval ADDA_HANDLER_RET_OK 数据发送成功
 * @retval ADDA_HANDLER_RET_ERROR 参数无效或队列已满
 */
adda_handler_ret_t adda_queue_send   (void* queue_handle, 
									  void* item, 
									  uint32_t timeout_ms )
{
	if( NULL     == queue_handle ||
		NULL     == item	     ||
		timeout_ms >	0xFFFF     )
	{
		return ADDA_HANDLER_RET_ERROR;
	}
	
	if( pdTRUE == xQueueSendToBack(queue_handle,
								   item,
								   timeout_ms) )
	{
		return ADDA_HANDLER_RET_OK;
	}
	else
	{
		return ADDA_HANDLER_RET_ERROR;
	}
}

/**
 * @brief 从ADDA事件队列接收数据
 * @details 封装FreeRTOS的xQueueReceive函数，从队列头部接收数据
 * 
 * @param[in] queue_handle 队列句柄
 * @param[out] item 接收数据的缓冲区指针
 * @param[in] timeout_ms 超时时间（毫秒）
 * 
 * @return adda_handler_ret_t 操作结果
 * @retval ADDA_HANDLER_RET_OK 数据接收成功
 * @retval ADDA_HANDLER_RET_ERROR 参数无效或超时
 */
adda_handler_ret_t adda_queue_receive(void* queue_handle, 
									  void* item, 
									  uint32_t timeout_ms )
{
	if( NULL     == queue_handle ||
		NULL     == item	       )
	{
		return ADDA_HANDLER_RET_ERROR;
	}
	
	if( pdTRUE == xQueueReceive(queue_handle,
								item,
								timeout_ms) )
	{
		return ADDA_HANDLER_RET_OK;
	}
	else
	{
		return ADDA_HANDLER_RET_ERROR;
	}
}

/**
 * @brief ADDA处理器OS接口结构体实例
 * @details 整合所有OS相关接口函数，提供给ADDA处理器使用
 */
adda_handler_os_t   os = 
{
	.os_delay_ms        = &os_delay,
	.adda_queue_create  = &adda_queue_create,
	.adda_queue_delete  = &adda_queue_delete,
	.adda_queue_send    = &adda_queue_send,
	.adda_queue_receive = &adda_queue_receive,
};

/**
 * @brief OS临界区接口结构体实例
 * @details 绑定FreeRTOS的临界区保护函数
 */
os_critical_t     os_critical = 
{
	.pfenter_critical = vPortEnterCritical,
	.pfexit_critical  = vPortExitCritical,
};

/**
 * @brief DAC硬件接口结构体实例
 * @details 绑定DAC相关的HAL库函数和硬件句柄
 */
bsp_dac_t           dac1      = 
{
	.pfinit   = (void (*)(void *))MX_DAC_Init,
	.pfdeinit = (void (*)(void *))HAL_DAC_DeInit,
	.hdac     = &hdac,
	.pfstart  = (void *(*)(void *, uint32_t,
						   const uint32_t *,
						   uint32_t,
						   uint32_t))HAL_DAC_Start_DMA,
	.pfstop   = (void *(*)(void *, uint32_t))HAL_DAC_Stop,
};

/**
 * @brief ADC硬件接口结构体实例
 * @details 绑定ADC相关的HAL库函数和硬件句柄
 */
bsp_adc_t		adc1      =
{
	.pfinit   = (void (*)(void *))MX_ADC1_Init,
	.pfdeinit = (void (*)(void *))HAL_ADC_DeInit,
	.hadc     = &hadc1,
	.pfstart  = (void *(*)(void *,
						   uint32_t *,
						   uint32_t))HAL_ADC_Start_DMA,
	.pfstop   = (void *(*)(void *))HAL_ADC_Stop_DMA,
};

/**
 * @brief ADDA系统输入参数结构体实例
 * @details 整合所有ADDA处理器所需的硬件接口和OS接口
 */
adda_input_t adda_input = 
{
	.time_base   = &time_base,
	.dac         = &dac1,
	.adc         = &adc1,
	.os          = &os,
};
